<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>The TinyWidgets Tutorial: The Widgets</TITLE>
 <LINK HREF="tnw-tut-6.html" REL=next>
 <LINK HREF="tnw-tut-4.html" REL=previous>
 <LINK HREF="tnw-tut.html#toc5" REL=contents>
</HEAD>
<BODY>
<A HREF="tnw-tut-6.html">Next</A>
<A HREF="tnw-tut-4.html">Previous</A>
<A HREF="tnw-tut.html#toc5">Contents</A>
<HR>
<H2><A NAME="s5">5. The Widgets</A></H2>

<H2><A NAME="TN_WINDOW"></A> <A NAME="ss5.1">5.1 TN_WINDOW</A>
</H2>

<P>
<P>
<H3>Introduction</H3>

<P>This is the Window widget. For every application you will need atleast one window. All other widgets can be added to a Window widget. The parent for the window widget must be the widget returned by <I>tnAppInitialize</I>. 
<P>
<H3>Specifications</H3>

<P>A Window can take the following optional properties in the call to <I>tnCreateWidget</I>.
<UL>
<LI>TN_BGCOLOR : Background color for the window (defaults to grey).</LI>
<LI>TN_CAPTION : The window title. The default window title is "Window".</LI>
</UL>
<P>Examples:
<P>A window specification with a window title "My App"
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
window1 = tnCreateWidget(TN_WINDOW,main_widget,50,50,TN_HEIGHT,200,TN_WIDTH,200,TN_CAPTION,"My App",TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be specified when calling <I>tnRegisterCallBack</I> for a window.
<UL>
<LI> CLICKED : Event occurs when user clicks on the window.</LI>
<LI> CLOSED : Event occurs when user clicks on the close button of the window. If the user wishes to terminate his application with the closing of a particular window, he must call 
<A HREF="tnw-tut-3.html#tnEndApp">tnEndApp</A>
 in this callback.</LI>
</UL>
<P>
<H3>Utility Functions</H3>

<P>The following utility functions have been provided to manipulate the properties of the window
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
tnGetClickedPos(TN_WIDGET *window, int *x, int *y)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Returns the x and y co-ordinates where the last clicked event occured on the window. The co-ordinates are relative to the upper left corner of the window.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
tnGetWindowTitle(TN_WIDGET *window, char *title)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Returns : The currently set title of the window.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
tnSetWindowTitle(TN_WIDGET *window, char *title)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Sets the window title as specified.
<P>
<P>
<H2><A NAME="TN_BUTTON"></A> <A NAME="ss5.2">5.2 TN_BUTTON</A>
</H2>

<P>
<P>
<H3>Introduction</H3>

<P>This is the Push Button widget. It can be placed inside a window widget. The push button supports either a text caption or a pixmap as its face.
<P>
<H3>Specifications</H3>

<P>By default a button has a caption which is set to "Button".
The following properties can be specified optionally for a button while calling <I>tnCreateWidget</I>
<UL>
<LI>TN_PIXMAP   : Set to TN_TRUE if pixmap on the button is to be specified.</LI>
<LI>TN_CAPTION  : Specifies the caption to be used when TN_PIXMAP is not set.</LI>
<LI>TN_FILENAME : Specifies the pixmap filename if TN_PIXMAP is set.</LI>
</UL>

Examples:
<P>A  button specification with pixmap file "/usr/share/pixmaps/foo.xpm"
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mybutton=tnCreateWidget(TN_BUTTON,mywindow,10,10,TN_HEIGHT,50,TN_WIDTH,50,
                        TN_PIXMAP,TN_TRUE,
                        TN_FILENAME,"/usr/share/pixmaps/foo.xpm",
                        TN_END);
                        
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>A button with default values and a caption "TinyWidgets"
<BLOCKQUOTE><CODE>
<HR>
<PRE>

mybutton=tnCreateWidget(TN_BUTTON,mywindow,10,10,
                        TN_CAPTION,"TinyWidgets",
                        TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be specified while calling <I>tnRegisterCallBack</I> for a button.
<UL>
<LI>CLICKED : Event occurs when user clicks and releases the button.</LI>
</UL>
<P>
<H3>Utility Functions</H3>

<P>The following utility functions can be used for a button to access and change its properties.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetButtonPressed(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Get the button number for the last CLICKED event on the button.
<P>Returns: A mask containing set bits for number of mouse buttons which were involved in the clicked event.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetButtonPixmap(TN_WIDGET *widget,char *filename)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets pixmap for the face of a button.
<P>Returns: 1 on success, -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnRemoveButtonPixmap(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Removes a pixmap on the face of the button and sets empty caption.
<P>Returns: 1 on success, -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetButtonCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets a caption on the face of a button.
<P>Returns: 1 on success, 0 if a pixmap already present on button, -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetButtonCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Copies the caption of the button into the string pointed by <I>caption</I>
<P>Returns: 1 on success, -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
TN_HASPIXMAP(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: This is a macro that returns 1 if the face of the button is a pixmap , 0 otherwise.
<P>Returns: 1 if face has a pixmap, 0 otherwise.
<H2><A NAME="TN_LABEL"></A> <A NAME="ss5.3">5.3 TN_LABEL</A>
</H2>

<P>This is the static label widget. It provides the facility of adding static text labels to a window widget. The label supports various fonts,font sizes and colors. By default the label is black colored and automatically resizes itself according to the font size.
<H3>Specifications</H3>

<P>By default a label has a caption which is set to "Label".
The following properties can be specified optionally for a label while calling <I>tnCreateWidget</I>
<P>
<UL>
<LI>TN_CAPTION  : Specifies the caption to be used for the label.</LI>
<LI>TN_FONTNAME : Specifies the name of the font to be used for the label.</LI>
<LI>TN_FONTSIZE : Specifies the font size to be used for the label.</LI>
<LI>TN_FGCOLOR  : Specifies the foreground color to be used for the label.</LI>
<LI>TN_BGCOLOR  : Specifies the background color to be used for the label.</LI>
</UL>
<P>Examples:
<P>A  label specification with foreground black,background white and caption "Hello World!"
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mylabel=tnCreateWidget(TN_LABEL,mywindow,10,10,
                        TN_CAPTION,"Hello World!",
                        TN_BGCOLOR,TN_RGB(255,255,255),
                        TN_FGCOLOR,TN_RGB(0,0,0),
                        TN_END);
                        
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>A label with  a caption "TinyWidgets",and with <I>courier new</I> font, size 16 points 
<BLOCKQUOTE><CODE>
<HR>
<PRE>

mylabel=tnCreateWidget(TN_LABEL,mywindow,10,10,
                        TN_FONTNAME,"cour",
                        TN_FONTSIZE,16,
                        TN_CAPTION,"TinyWidgets",
                        TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be specified while calling <I>tnRegisterCallBack</I> for a label.
<UL>
<LI>CLICKED : Event occurs when user clicks and releases the label.</LI>
</UL>
<P>
<H3>Utility Functions</H3>

<P>The following utility functions can be used for a label to access and change its properties.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetLabelCaption(TN_WIDGET *widget, char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the caption for a label to <I>caption</I>
<P>Returns: 1 on success, -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetLabelCaptionColor(TN_WIDGET *widget, TN_COLOR color)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the color of the caption to <I>color</I> for the label
<P>Returns: 1 on success, -1 on error.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
TN_COLOR tnGetLabelCaptionColor(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the color of caption for the label 
<P>Returns: The color of caption on success , -1 on error.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetLabelCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the caption for the label.
<P>Returns: 1 on success, -1 on failure.
<H2><A NAME="TN_CHECKBUTTON"></A> <A NAME="ss5.4">5.4 TN_CHECKBUTTON</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the checkbutton widget. It can be placed inside a window widget. It is like a toggle button.
<H3>Specification</H3>

<P>The following properties can be optionally set via the <I>tnCreateWidget</I> call:
<UL>
<LI> TN_CAPTION: The text to be displayed in the check button. It defaults to "Check Button"</LI>
<LI> TN_FONTNAME: The font (if installed) in which the text is to be displayed.</LI>
<LI> TN_FONTSIZE: The size of the font in which the text is to be displayed.</LI>
<LI> TN_FGCOLOR: The color in which the text is to be displayed.</LI>
<LI> TN_BGCOLOR: The background color of the checkbutton.</LI>
</UL>

Examples:
<P>A checkbutton with a caption of "TinyWidgets", to be displayed in Courier Font and fontsize 8.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
checkbtn0 = tnCreateWidget(TN_CHECKBUTTON,window0,35,45,TN_FONTNAME,"cour",TN_FONTSIZE,8,TN_CAPTION,"TinyWidgets",TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be registered for a checkbutton via <I>tnRegisterCallBack</I>.
<UL>
<LI> CLICKED : This event occurs when the user clicks on the checkbutton.</LI>
</UL>
<H3>Utility Functions</H3>

<P>The following utility functions have been provided to manipulate the checkbutton
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetCheckButtonCaption(TN_WIDGET *checkbutton, char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Returns the currently set caption of the checkbutton.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetCheckButtonCaption(TN_WIDGET *checkbutton, char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Sets the caption of the checkbutton.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetCheckButtonStatus(TN_WIDGET *checkbutton, TN_BOOL status)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Sets the status of the checkbutton as specified.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
TN_CHECKBUTTONACTIVE(checkbutton)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description :  A macro which tests if the checkbutton is active.
<P>
<P>
<H2><A NAME="TN_RADIOBUTTONGROUP"></A> <A NAME="ss5.5">5.5 TN_RADIOBUTTONGROUP</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the radio button group widget. It can be placed inside a window widget. A radio button group needs to be created for grouping radio buttons. All radio buttons in a group will behave in a mutually exclusive manner. 
<H3>Specification</H3>

<P>The default caption for a radio button group is "RadioButton Group". The following properties can be optionally set via the <I>tnCreateWidget</I> call:
<UL>
<LI>TN_CAPTION : The radio button group caption text.</LI>
</UL>
<H3>Callbacks</H3>

<P>The following callbacks can be registered via <I>tnRegisterCallBack</I>
<UL>
<LI>CLICKED : a pointer click occurs anywhere withing the radio button group.</LI>
<LI>SELECTED : a radio button within the group has been selected.</LI>
</UL>
<H3>Utility Functions</H3>

<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetRadioButtonGroupCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the radio button group caption text.
<P>Returns: 1 on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetRadioButtonGroupCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the radio button group caption.
<P>Returns: 1 on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetRadioButtonGroupClickedPos(TN_WIDGET *widget,int *x,int *y)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Returns the x &amp; y co-ordinates at which the pointer is clicked inside the radio button group.
<P>Returns: 1 on success. -1 on failure.
<H2><A NAME="TN_RADIOBUTTON"></A> <A NAME="ss5.6">5.6 TN_RADIOBUTTON</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the radio button widget. It is to be placed inside a radio button group widget.
<H3>Specification</H3>

<P>The default caption for a radio button is "Radio Button". The following properties can be defined via the <I>tnCreateWidget</I> call
<UL>
<LI>TN_CAPTION : The radio button caption.</LI>
</UL>
<H3>Utility Functions</H3>

<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetRadioButtonCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the caption text for the radio button.
<P>Returns: 1 on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetRadioButtonCaption(TN_WIDGET *widget,char *caption)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the radio button caption.
<P>Returns: 1 on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetRadioButtonStatus(TN_WIDGET *widget,TN_BOOL status)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the radio button status to selected (TN_TRUE) or unselected (TN_FALSE).
<P>Returns: 1 on success. -1 on failure.
<H2><A NAME="TN_TEXTBOX"></A> <A NAME="ss5.7">5.7 TN_TEXTBOX</A>
</H2>

<P>
<H3>Introduction</H3>

<P><B><I>The current textbox implementation although is almost usable is still under development. The user is advised to use the textbox widget with care.</I></B>
<P>This is the textbox widget. The textbox provides an editable text box on a window. Currenltly TinyWidgets supports single line (text entry field) and multiline textboxes(text areas). The textbox uses many special keys and hence relies on the scancode driver of microwindows. It has <B>NOT</B> been tested on other keyboard drivers and we wish to state clearly that it may not work with them. By default the textbox is a single line textbox with no default text.
<H3>Specifications</H3>

<P>The following properties can be specified optionally for a textbox while calling <I>tnCreateWidget</I>
<UL>
<LI>TN_TEXTBOXTYPE : Choose either of TN_SINGLE_LINE or TN_MULTI_LINE.</LI>
<LI>TN_DEFAULTTEXT : Sets the default(initial) text for the textbox.</LI>
<LI>TN_FONTNAME    : Selects the font to be used in the textbox.</LI>
<LI>TN_FONTSIZE    : Chooses the size of the font.</LI>
<LI>TN_FGCOLOR     : Sets the foreground color of text.</LI>
</UL>

Examples:
<P>A single line textbox with font <I>Times New Roman</I>, size 16 points and default text set to "Hello World!"
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mytextbox=tnCreateWidget(TN_TEXTBOX,mywindow,10,10,
                         TN_TEXTBOXTYPE,TN_SINGLE_LINE,
                         TN_DEFAULTTEXT,"Hello World!",
                         TN_FONTNAME,"times",
                         TN_FONTSIZE,16,
                         TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>A simple multiline textbox with no default text.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mytextbox=tnCreateWidget(TN_TEXTBOX,mywindow,10,10,
                         TN_TEXTBOXTYPE,TN_MULTI_LINE,
                         TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
                
<H3>Callbacks</H3>

<P>The following callbacks can be specified while calling <I>tnRegisterCallBack</I> for a textbox.
<UL>
<LI>GOTFOCUS    :Event occurs typically when user clicks in a textbox.</LI>
<LI>LOSTFOCUS   :Event occurs typically when a user clicks elsewhere.</LI>
<LI>MODIFIED    :Event occurs when keyboard activity modifies text in the textbox.</LI>
</UL>
<P>
<H3>Utility Functions</H3>

<P>The following utility functions can be used for a textbox to access and change its properties.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
char * tnGetText(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Returns the text in a buffer contained in the textbox. The user has to free the returned buffer.
<P>Returns: A pointer to a character buffer containing the characters in the textbox on success, NULL on error.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetText(TN_WIDGET *widget,char *text)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the text in the textbox to <I>text</I>
<P>Returns: 1 on success. -1 on failure.
<H2><A NAME="TN_SCROLLBAR"></A> <A NAME="ss5.8">5.8 TN_SCROLLBAR</A>
</H2>

<P>This is the scrollbar widget. These scrollbars can be placed on windows. The scrollbar widget has two orientations, namely TN_HORIZONTAL and TN_VERTICAL. By default the scrollbar is is a vertical scrollbar, with range set from 0 to 100 and linestep = 1 , pagestep = 5. The thumb can also  be dragged to an arbitary position using the mouse.
<P>
<H3>Specifications</H3>

<P>The following properties can be specified optionally for a scrollbar while calling <I>tnCreateWidget</I>
<P>
<UL>
<LI>TN_ORIENTATION      :Selects one of TN_VERTICAL and TN_HORIZONTAL.</LI>
<LI>TN_MINVAL           :Sets the value for the scrollbar when it is at minimum scrolled position</LI>
<LI>TN_MAXVAL           :Sets the value for the scrollbar when it is at maxmum scrolled position</LI>
<LI>TN_LINESTEP :Sets the increment per single line of scrolling.</LI>
<LI>TN_PAGESTEP :Sets the increment per a page of scrolling.</LI>
</UL>
<P>Example: 
A vertical scrollbar with range 50 to 100 and pagestep = 10 , linestep = 2 
<BLOCKQUOTE><CODE>
<HR>
<PRE>
myscrollbar=tnCreateWidget(TN_SCROLLBAR,mywindow,10,10,
                           TN_ORIENTATION,TN_VERTICAL,
                           TN_MINVAL,50,
                           TN_MAXVAL,100,
                           TN_LINESTEP,2
                           TN_PAGESTEP,10,
                           TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>

A horizontal scrollbar with default properties
<BLOCKQUOTE><CODE>
<HR>
<PRE>
myscrollbar=tnCreateWidget(TN_SCROLLBAR,mywindow,10,10,
                           TN_ORIENTATION,TN_HORIZONTAL,
                           TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be specified while calling <I>tnRegisterCallBack</I> for a scrollbar.
<P>
<UL>
<LI>CLICKED             :This event occurs when user clicks on any part of the scrollbar.</LI>
</UL>
<P>
<H3>Utility functions </H3>

<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetScrollbarOrientation(TN_WIDGET *widget,int *orientation)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets *orientation to either of TN_HORIZONTAL or TN_VERTICAL
<P>Returns: 1 on success, -1 on error
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetScrollbarOrientation(TN_WIDGET *widget,int orientation)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the orientation of scrollbar to <I>orientation</I>
<P>Returns: 1 on success, -1 on error
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetScrollRange(TN_WIDGET *widget,int *minval,int *maxval)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the range of scrollbar into *minval and *maxval
<P>Returns: 1 on success, -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetScrollRange(TN_WIDGET *widget,int minval,int maxval)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the range of scrollbar from <I>minval</I> to <I>maxval</I>
<P>Returns: 1 on success, -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetScrollStepSizes(TN_WIDGET *widget,int *pagestep,int *linestep)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the pagestep and linestep of scrollbar into *pagestep and *linestep respectively
<P>Returns: 1 on success , -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetScrollStepSizes(TN_WIDGET *widget,int pagestep,int linestep)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the pagestep and linestep of scrollbar to <I>pagestep</I> and <I>linestep</I> respectively
<P>Returns: 1 on success , -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetThumbPosition(TN_WIDGET *widget,int position)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the position of the thumb to <I>position</I>
<P>Returns: 1 on success , -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetThumbPosition(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Description: Gets the position of the thumb 
<P>Returns: Thumb position on success , -1 on failure.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetLastScrollEvent(TN_WIDGET *scrollbar)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Gets the last scrolling event that occured with the scrollbar.
<P>Returns: On success returns one of 
<UL>
<LI>TN_SCROLL_NOSCROLL</LI>
<LI>TN_SCROLL_LINEUP</LI>
<LI>TN_SCROLL_LINEDOWN</LI>
<LI>TN_SCROLL_PAGEUP</LI>
<LI>TN_SCROLL_PAGEDOWN</LI>
<LI>TN_SCROLL_THUMBMOVE</LI>
</UL>

On failure returns -1
<P>
<P>
<H2><A NAME="TN_PROGRESSBAR"></A> <A NAME="ss5.9">5.9 TN_PROGRESSBAR</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the progressbar widget. It can be placed inside a window widget.
<H3>Specifications</H3>

<P>A progress bar can be of type :
<UL>
<LI>Continuous</LI>
<LI>Discrete</LI>
</UL>

A continous progressbar is created by default. The following properties can be optionally specified for a progressbar via the a call to <I>tnCreateWidget</I>
<UL>
<LI>TN_STEPSIZE : The step size for the discrete progressbar.</LI>
<LI>TN_FILLCOLOR : The fill color for the bar.</LI>
<LI>TN_FONTNAME : The font to be used for the text which indicate completion status.</LI>
<LI>TN_FONTSIZE : The font size for the above mentioned text.</LI>
</UL>
<H3>Utility functions</H3>

<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
void tnProgressBarUpdate(TN_WIDGET *pbar, int value)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Set the value for the progress bar.
Returns: nothing
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetProgressBarValue(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description:  Returns the current value for the progress bar.
<P>Returns: The current value on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetProgressBarFillColor(TN_WIDGET *widget,TN_COLOR color)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Set the current fill color to "color".
<P>Returns: 1 on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
TN_COLOR tnGetProgressBarFillColor(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Returns the fill color.
<P>Returns: The current fill color on success. -1 on failure.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetProgressBarStepSize(TN_WIDGET *widget,int stepsize)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Sets the step size for a discrete progress bar.
<P>Returns: 1 on success. -1 on failure; will return -1 for a continuous progress bar.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetProgressBarStepSize(TN_WIDGET *widget)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: Returns the current step size.
<P>Returns: The current step size on success. -1 on failure ; will return -1 for a continuous progress bar.
<H2><A NAME="TN_LISTBOX"></A> <A NAME="ss5.10">5.10 TN_LISTBOX</A>
</H2>

<P>
<P>
<H3>Introduction</H3>

<P>This is a listbox widget which allows the user to display a list of items on the screen.
<P>
<H3>Specifications</H3>

<P>The following optional properties can be specified while calling <I>tnCreateWidget</I>.
<UL>
<LI> TN_FONTNAME : The name of the font to be used to display the List items. This property will be valid only if the specified fontname is installed and Nano-X is compiled with freetype support.</LI>
<LI> TN_FONTSIZE : The size of the font to be used.</LI>
<LI> TN_FGCOLOR : The color to be used for displaying the ListItems in the Listbox.</LI>
<LI> TN_COUNT : The number of items to be displayed in the Listbox</LI>
<LI> TN_LISTITEMS : The list of items to be displayed in the ListBox. This property will be valid only if the TN_COUNT property is specified correctly.</LI>
<LI> TN_RESIZE : This property, if set to TN_TRUE, causes the listbox to be resized whenever the number of items in the listbox does not fit in the specified height. By default it is set to TN_TRUE.</LI>
</UL>

Examples:
<P>A listbox specification with default properties and 5 Items to be displayed.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
 
char *s[] = {"Monday","Tuesday","Wednesday","Thursday","Friday"};
listbox1 = tnCreateWidget(TN_LISTBOX,window1,10,20,TN_COUNT,5,TN_LISTITEMS,s,TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>An empty Listbox with Times Font to be used to display the List Items.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
listbox2 = tnCreateWidget(TN_LISTBOX,window1,20,30,TN_FONTNAME,"times",TN_FONTSIZE,12,TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be specified while calling <I>tnRegisterCallBack</I> for a listbox.
<UL>
<LI> CLICKED : Event occurs when user clicks in the listbox.</LI>
</UL>
<P>
<H3>Utility Functions</H3>

<P>The following utility functions have been provided for manipulating the listbox.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetSelectedListItems(TN_WIDGET *widget, char ***listitems,int *count)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Allocates space and returns the selected items in the listbox(multiple items can be selected using the Cntrl key modifier). Count contains the number of selected items. The user is expected to free the Listitems after he has finished using them.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetAllListItems(TN_WIDGET *listbox, char ***items, int *count)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Returns all the items in the Listbox. The user is again expected to free the list of items.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetSelectedListNum(TN_WIDGET *listbox)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Returns: The number of items selected in the Listbox, -1 if there is an error.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetSelectedListPos(TN_WIDGET *listbox,int **pos,int *count)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Returns the indices of the selected list items and their count. The pos array is allocated in the function and hence the user must free it after he is finished.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetListItemPos(TN_WIDGET *listbox, char *item)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Given an item, it returns its index in the Listbox.
<P>Returns : -1 if the item was not found in the Listbox, or some error occured.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnAddItemToListBox(TN_WIDGET *listbox, char *item)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description :  Adds the item to the end of the list of items currently in the Listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnAddItemToListBoxAt(TN_WIDGET *listbox, char *item, int pos)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Adds the item to the list of items currently in the Listbox at the position specified by pos. If pos is greater than the number of items currently in the listbox then the item is added to the end of the list of items.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnDeleteItemFromListBox(TN_WIDGET *listbox, char *item)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Deletes the item from the list of items currently displayed in the listbox.
<P>Returns: -1 if the item was not found in the Listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnDeleteItemFromListBoxAt(TN_WIDGET *listbox, int pos)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Deletes the item from the Listbox whose index is specified by pos. 
<P>Returns: -1 if pos is greater than the number of items in the listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnDeleteSelectedItems(TN_WIDGET *listbox)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Deletes all the items in the listbox which have been selected by the user.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnDeleteAllItemsFromListBox(TN_WIDGET *listbox)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Deletes all the items from the Listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetSelectedListItem(TN_WIDGET *listbox,char *item, TN_BOOL selected)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Sets the status of the item in the listbox as specified by the selected parameter (TN_TRUE = selected, TN_FALSE = unselected).
<P>Returns : -1 if the item is not found in the Listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetSelectedListItemAt(TN_WIDGET *listbox, int pos, TN_BOOL selected)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Sets the status to selected, of the item whose index is specified by pos.  
<P>Returns : -1 if the index is specified is greater than the number of items in the listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnListItemsLineUp(TN_WIDGET *widget, int number)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Scrolls the list of items displayed in the listbox up by the number of lines specified. Work only if the TN_RESIZE property of the listbox is set to TN_FALSE. 
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnListItemsLineDown(TN_WIDGET *widget, int number)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description :  Scrolls the list of items displayed in the listbox up by the number of lines specified. Works only if the TN_RESIZE property of the listbox is set to TN_FALSE. 
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetListTop(TN_WIDGET *listbox)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Gets the index of the item displayed at the top of the Listbox. Works only if the TN_RESIZE property of the listbox is set to TN_FALSE. 
The above three functions can be used in conjunction with the scrollbar to scroll the items displayed in the Listbox.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnGetListBoxResize(TN_WIDGET *listbox, TN_BOOL *resize)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Returns the currently set resize property of the listbox
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int tnSetListBoxResize(TN_WIDGET *listbox, TN_BOOL resize)
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description : Sets the resize property of the listbox as sepcified.
<P>
<H2><A NAME="TN_PICTURE"></A> <A NAME="ss5.11">5.11 TN_PICTURE</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the picture widget and allows the user to display images(BMP, JPEG, GIF etc) in a picture container. 
<P>
<H3>Specifications</H3>

<P>The following optional properties can be specified for a picture while calling <I>tnCreateWidget</I>
<UL>
<LI> TN_FILENAME : The filename of the image to be displayed in the container. The full path of the filename must be specified.</LI>
<LI> TN_STRETCH : This is a Boolean value. If True then the container will be resized to the size of the image to be displayed. If this value is false the image will be resized to the size of the container.By default this property is set to TN_FALSE. </LI>
</UL>

Examples:
<P>A picture specification with the image file "/root/Images/liz.jpg" where the container is resized to the size of the image.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mypicture=tnCreateWidget(TN_PICTURE,window0,50,50,TN_FILENAME,"/root/Images/liz.jpg",TN_STRETCH,TN_TRUE,TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Callbacks</H3>

<P>The following callbacks can be specified while calling <I>tnRegisterCallBack</I> for a Picture.
<UL>
<LI> CLICKED : Event occurs when user clicks on the Picture container.</LI>
</UL>
<P>
<H3>Utility Functions</H3>

<P>
<P>The following utility functions have been provided for the Picture widget to access and change its properties. 
<BLOCKQUOTE><CODE>
 
<HR>
<PRE>
 int tnGetPictureProps(TN_WIDGET *picture, TN_BOOL *stretch, char **filename) 
</PRE>
<HR>
 
</CODE></BLOCKQUOTE>

Description: This function returns the currently set properties of the picture i.e. Stretch and the filename of the currently displayed image in the picture. The user is expected to free the filename string which this function allocates. 
<P>Returns: 1 on success, -1 on failure.
<P>
<BLOCKQUOTE><CODE>
 
<HR>
<PRE>
 int tnSetPicture(TN_WIDGET *picture, char *filename) 
</PRE>
<HR>
</CODE></BLOCKQUOTE>

Description: This function loads the image specified by filename into the picture widget. 
<P>Returns: 1 if succesful, -1 in case of error. 
<P>
<BLOCKQUOTE><CODE>
 
<HR>
<PRE>
 int tnSetPictureStretch(TN_WIDGET *picture,GR_BOOL stretch) 
</PRE>
<HR>
 
</CODE></BLOCKQUOTE>

Description: This function sets the Stretch property of the picture widget. 
<P>
<BLOCKQUOTE><CODE>
 
<HR>
<PRE>
 int tnPictureDup(TN_WIDGET *destpic,TN_WIDGET *srcpic) 
</PRE>
<HR>
 
</CODE></BLOCKQUOTE>

Description: This function duplicates the image displayed in the srcpic widget into the destpic widget. This is especially useful in order to save memory. By using the Duplication of the image it is not loaded by the server again. 
<P>
<BLOCKQUOTE><CODE>
 
<HR>
<PRE>
 int tnGetPictureImageProps(TN_WIDGET *picture, TN_IMAGE_INFO *iinfo) 
</PRE>
<HR>
 
</CODE></BLOCKQUOTE>

Description: Fills the iinfo structure with the following properties relevant to the image displayed in the picture container. 
<UL>
<LI> Height of the image.</LI>
<LI> Width of the image.</LI>
<LI> Bits per pixel.</LI>
<LI> Bytes per pixel.</LI>
</UL>
<P>
<H2><A NAME="TN_MENUBAR"></A> <A NAME="ss5.12">5.12 TN_MENUBAR</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the menu bar widget. It is to be placed in a window widget. 
<H3>Specification</H3>

<P>A call to <I>tnCreateWidget</I> will create a horizontal menu bar, which is aligned to the window top and resized to the window width, by default. The x &amp; y position can optionally be specified.
<P>Examples:
The following call will create a default menu bar (aligned to the window top) 
<BLOCKQUOTE><CODE>
<HR>
<PRE>
menu_bar = tnCreateWidget(TN_MENUBAR,window,0,0,TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<H2><A NAME="TN_POPUPMENU"></A> <A NAME="ss5.13">5.13 TN_POPUPMENU</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the popup menu widget. It allows for creation of popup menus. It is to be placed inside a menubar widget.
A popup menu widget must be defined for providing pull down menu functionality. 
<H3>Specification</H3>

<P>The following properties can be set via the <I>tnCreateWidget</I> call
<UL>
<LI>TN_CAPTION : The label for the popup menu.</LI>
<LI>TN_EXCLUSIVE : This atrribute if set makes the subsequently added checkable menu items behave in a mutually exclusive manner.</LI>
</UL>

Examples:
The following call will create a default popup menu with the label "File". (The TN_AUTO keyword indicates that positioning will be automatically handled).
<BLOCKQUOTE><CODE>
<HR>
<PRE>
popup_menu = tnCreateWidget(TN_POPUPMENU,menu_bar,TN_AUTO,TN_AUTO,TN_CAPTION,"File",TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<H2><A NAME="TN_CASCADEDMENU"></A> <A NAME="ss5.14">5.14 TN_CASCADEDMENU</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the cascade menu widget. It is to be placed inside a popup menu widget. It provides cascade (horizontal menus) functionality. A cascade menu will be displayed as a label with a rightward pointing arrow.
<H3>Specification</H3>

<P>The following properties can be set via the <I>tnCreateWidget</I> call
<UL>
<LI>TN_CAPTION : The label for the cascade menu.</LI>
<LI>TN_EXCLUSIVE : This atrribute if set makes the subsequently added checkable menu items behave in a mutually exclusive manner.</LI>
</UL>

Examples:
The following call will create a default cascade menu atached to a popup menu, with the label "Tools". (The TN_AUTO keyword indicates that positioning will be automatically handled).
<BLOCKQUOTE><CODE>
<HR>
<PRE>
cascade_menu = tnCreateWidget(TN_CASCADEMENU,popup_menu,TN_AUTO,TN_AUTO,TN_CAPTION,"Tools",TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<H2><A NAME="TN_MENUITEM"></A> <A NAME="ss5.15">5.15 TN_MENUITEM</A>
</H2>

<P>
<H3>Introduction</H3>

<P>This is the menu item widget. It can be placed inside any of the following
<UL>
<LI>Menu Bar</LI>
<LI>PopUp Menu</LI>
<LI>Cascade Menu</LI>
</UL>

It is the basic menu item which when clicked, a programmer defined action can be taken.
<H3>Specification</H3>

<P>The following properties may be set via the <I>tnCreateWidget</I> call
<UL>
<LI>TN_CAPTION : The label for the menu item.</LI>
<LI>TN_CHECKABLE : This attribute, if set, causes the menu item to toggle state when clicked. A dot appears against a selected menu item. (This can be used in conjunction with the TN_EXCLUSIVE flag for the popup &amp; cascade menus to provide a mutually exclusive group of menu items).</LI>
</UL>

Examples:
The following call will create a basic menu item with the label "Open", within a popup menu. (TN_AUTO for the x &amp; y positions indicates automatic positioning).
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mitem0 = tnCreateWidget(TN_MENUITEM,popup_menu,TN_AUTO,TN_AUTO,TN_CAPTION,"Open",TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>The following call will create a checkable (toggle) menu item within a cascade menu.
<BLOCKQUOTE><CODE>
<HR>
<PRE>
mitem1 = tnCreateWidget(TN_MENUITEM,cascade_menu,TN_AUTO,TN_AUTO,TN_CAPTION,"Tool1",TN_CHECKABLE,TN_TRUE,TN_END);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<H3>Callbacks</H3>

<P>The following callback(s) can be registered via the <I>tnRegisterCallBack</I> call
<UL>
<LI>CLICKED : Specifies the action routine to be called when the menu item is clicked.</LI>
</UL>
<HR>
<A HREF="tnw-tut-6.html">Next</A>
<A HREF="tnw-tut-4.html">Previous</A>
<A HREF="tnw-tut.html#toc5">Contents</A>
</BODY>
</HTML>
